ソフトウェアアーキテクチャの基礎輪読会 19章
日付：2023/11/29
章：19
調査者：iNoma.icon
この章から、第Ⅲ部「テクニックとソフトスキル」に入る
技術的な側面だけではない
開発チームを導きステークホルダを納得させるテクニックやソフトスキルについて
章のまとめ
どんな内容が書かれているか？
アーキテクチャ決定に関するアンチパターン
資産防御 アンチパターン
iNoma.icon「そもそもアーキテクチャ決定を下せない状態」
グラウンドホッグデー アンチパターン
iNoma.icon「アーキテクチャ決定の根拠が明確でない状態」
メール駆動アーキテクチャ アンチパターン
iNoma.icon「アーキテクチャ決定が効果的に伝達されていない状態」
アーキテクチャ上重要なもの
技術的な決定とみなされがちなアーキテクチャ決定について
アーキテクチャデシジョンレコード（ADR）
アーキテクチャ決定がいかに行われたかのログでありドキュメント
アーキテクチャ決定に関するアンチパターン
資産防御 アンチパターン
選択を誤ることを恐れて、アーキテクチャ決定を下すことを避けたり先延ばししたりする
解決策
正当であると検証するのに十分な情報が得られるまで、決定を先延ばしにする
開発チームと継続的に協力する
特定の技術に関する問題の詳細をアーキテクトだけですべて把握するのは不可能
開発チームと密に連携することで、問題が発生しても対応しやすくなる
グラウンドホッグデー アンチパターン
ある決定が下された理由がわからずに繰り返し何度も議論されてしまう
iNoma.iconやっちゃいがち
解決策
ビジネス価値を提示する
5章では「ドメインの関心事からアーキテクチャ特性への翻訳」だったが、
ここでは「アーキテクチャ特性からドメインの関心事への翻訳」と考えて良さそう
iNoma.iconドキュメンテーションの話（ADR）にも繋がる問題
メール駆動アーキテクチャ アンチパターン
人々がアーキテクチャ決定を見失ったり、忘れたり、あるいは決定されたことさえ知らなかったりするために発生するアンチパターン
アーキテクチャ決定を効果的に伝えられているかが肝要
メールの文章がドキュメンテーションとして用いられている
kiri.iconこれあるなあ
iNoma.icon現代だとSlackなどのメッセージングツールも含みそう
以下、「メール」を「Slackのメッセージ」と読み替え可とします
解決策
アーキテクチャ決定をメールの本文に含めない
メールでは、重要な決定が行われたこと自体に言及
決定の詳細については、単一のドキュメンテーションへのリンクによって示す
アーキテクチャ決定に本当に関心のある人にだけ、それを伝える
開発者を含むステークホルダに、その内容を直接伝えるかどうかの判断
「直接その人に影響があるか」が基準のひとつ
例
こんにちは、たかっしーさん。サービス間通信に関する、あなたに直接影響のある重要な決定を行いました。
よければ、以下のリンクからその決定を参照してください。
アーキテクチャ上重要なもの
アーキテクトが責任を持つべき決定とは何か
以下の5つ
構造
非機能特性
依存関係
インターフェース
構築手法
構造
アーキテクチャのスタイルやパターンに影響する決定
例
「マイクロサービス間でデータを共有する」
iNoma.icon「第Ⅱ部 アーキテクチャスタイル」で紹介されているものに影響
非機能特性
依存関係
コンポーネントやサービス間の結合点
全体的なスケーラビリティ、モジュール性、アジリティ、テスト容易性、信頼性などに影響
インターフェース
サービスやコンポーネントへのアクセスやオーケストレーションの方法を指す
ゲートウェイ、統合ハブ、サービスバス、APIプロキシなどを介する
構築手法
プラットフォーム、フレームワーク、ツール、プロセスに関する決定
本質的には技術的決定だが、特にアーキテクチャに影響を与えるものを指す
アーキテクチャデシジョンレコード(ADR)
特定のアーキテクチャ決定を記述した短いテキストファイル
大抵 1~2pに収まる
AsciiDocやMarkdownで記述されることが多い
基本構造
タイトル
連番が振られ、短いフレーズによって紹介
例
「42. OrderサービスとPaymentサービスの間における非同期メッセージでの通信」
ステータス
提案済み、承認済み、破棄の３つから選択
「破棄」ステータスの存在を認めることで、アーキテクチャ決定の変遷をロギングできる
例
「42. OrderサービスとPaymentサービスの間における非同期メッセージでの通信」
ステータス：68に伴い破棄された
「68. OrderサービスとPaymentサービスの間におけるRESTでの通信」
ステータス：承認済み。42を破棄した
提案済み、承認済みステータスの存在は、アーキテクトが自分の仕事を自己承認できるか、上位者による承認が必要であるのかの議論を促す
努力レベルのコストの見積もりによって判断
アーキテクチャ決定にかかる推定時間にフルタイム当量を乗算することで見積もり 人月とは違うっぽい？
コストが一定額を越える場合には上位者に承認を委託する
コンテキスト
その決定の背景
具体的な状況や問題点を説明し、可能な代替案を簡潔に説明
アーキテクチャについて述べる場でもある
例
Orderサービスは。現在発注されている注文の決済を行うために、 Paymentサービスに情報を渡さなければならない。これはRESTまたは非同期メッセージを用いて行える。
決定
決定的かつ、命令的な形で記述する
その決定がなされた理由を記述することが非常に重要
例
p299 図19-5を参照
影響
アーキテクチャ決定の全体的な影響を文書化する
行ったアーキテクチャ決定が持つ悪影響が、メリットを上回っていないかを確認できる
トレードオフについての分析結果もここに述べる
例
p299 図19-5を参照
コンプライアンス
この決定が遵守されていることを、どのように確認するのかについて述べる
テストの内容、テスト箇所、テストの実行方法などを記述
手動でチェックするのか、適応度関数によって自動で行うのか、について決定する必要がある
備考
このADRに関するメタデータ
例
オリジナルの著者
承認日
承認者
置き換え日
最終更新日
変更点
最終更新内容
Gitなどで管理できるメタデータもあるが、ADRにも記述するのが便利であるらしい
ADRを保存する
ADRについては、個別のwikiやファイルを持つべきである
ADR文書を読む人全員が、ソースコードと同じGitレポジトリにアクセスできるとは限らない
例
p296 図19-3を参照
ドキュメントとしてのADR
アーキテクチャを図解する規格はいくつかある
一方でアーキテクチャを文書化する標準はない
ここで、ADRをアーキテクチャ文書の規格として運用する
標準のためにADRを用いる
ADRの決定セクションは、「標準」を管理するのに有用
その標準が存在する理由について述べることで、この標準が役に立つものであるかチェックできる
開発者が決定に従う可能性が高くなる
応用
code:sample.kt
質疑応答
ZOZOTOWNのブログ